hyperspell-mcp

Instructions

Implementation Reference

• src/hyperspell_mcp/server.py:114-120 (handler)

  The handler function that fetches and returns a specific document by ID using the Hyperspell API, converting the response to a Document model.
  def get_document(document_id: int) -> Document | Error: """Get a document from a collection""" # try: r = mcp.api.documents.get(document_id=document_id) return Document.from_pydantic(r) # except APIError as e: # return Error(error=e.__class__.__name__, message=e.message)
• src/hyperspell_mcp/server.py:113-113 (registration)

  Registers the get_document function as the 'Get Document' tool or resource with the MCP server.
  @mcp.tool_or_resource("document://{document_id}", name="Get Document")
• src/hyperspell_mcp/types.py:38-43 (schema)

  Pydantic-compatible data class defining the schema for the Document object returned by the tool.
  class Document(BaseModel): id: int title: str type: str summary: str
• src/hyperspell_mcp/types.py:53-56 (schema)

  Data class defining the schema for Error responses from the tool.
  class Error(BaseModel): error: str message: str
• src/hyperspell_mcp/types.py:7-29 (helper)

  Base class used by Document and Error for converting Pydantic models from the API to data classes, used in the handler.
  @dataclass class BaseModel: @overload @classmethod def from_pydantic(cls, model: PydanticBaseModel) -> Self: ... @overload @classmethod def from_pydantic(cls, model: Sequence[PydanticBaseModel]) -> list[Self]: ... @classmethod def from_pydantic( cls, model: PydanticBaseModel | Sequence[PydanticBaseModel] ) -> Self | list[Self]: """Convert a Pydantic model to a data class, selecting only the keys that are part of the data class.""" if isinstance(model, Sequence): return [cls.from_pydantic(m) for m in model] data = model.model_dump() # Only select the keys in data that are part of this data class data = {key: value for key, value in data.items() if key in cls.__annotations__} return cls(**data)